devfandomcom-20200223-history
Talk:DocTemplates
A good start That's a really good start. Two questions and a remark, though: * What does "tearable" mean? That's a word I hear for the first time. * And what is "literal" in the parameter template supposed to refer to? And I'm against separating description and examples. They should be intertwined and the decision about how much of each and in what order are needed should be made on a case by case basis. The template should not impose an arbitrary structure on the explanation. It's best to keep this part informal. That's what the jQuery docs do too btw. -- pecoes 16:29, November 07, 2012 (UTC) :Tearable isn't actually a word, but "-able" is a generic suffix with a standard definition and I'm not aware of tear having a verb-adjective form. It refers to tearing/ripping off. i.e. function something(f) { f(3); } var dfd = $.Deferred(); something(dfd.resolve); // tear the function off the deferred, works. var Cls = function() {}; Cls.prototype.demo = function(x) { this.x = x; } var c = new Cls(); something(c.demo); // Won't work, demo needs the this object, must be proxied :Literal refers to parameters that take literals like $.ajax or jQuery UI: $.ajax({ url: '/api.php', data: 'action=query&meta=userinfo&format=json', dataType: 'json' }).done(...); :In this case, saying $.ajax takes a "data" parameter isn't helpful, you need to describe all the fields of the literal as well (the properties that are accepted on the object). :The examples are supposed to be provided in the free-form general description of the JSMethod template. The example parameter is only on the usage template, I did that as it's intended for giving a very short reference example inside the method summary table. Writing a lot of code inside the summary table makes it much harder to read and less useful as a reference. Lunarity 02:43, November 8, 2012 (UTC) ::I see. "Tearable" is a good word then. I like it :) If it's not a term that's in general use it shouldn't be part of the template though. It would confuse more than help. -- pecoes 03:56, November 08, 2012 (UTC) Simplistic Approach Method Template We could just use JavaDoc style comments and call that the documentation. Template consists of 2 distinct pieces: Documentation and Examples. Keeping these two sections separate is a high priority to me. Main benefits: *Don't need to discuss exactly "how" things should be documented. Whatever you want to put in your comment header, that's the documentation. *Programmers can literally copy/paste their method signature/comment header if they have one. Then make an example. The example section can be used for lengthier discourse (paragraphs) if you want to write them. Method Template: would make something like... Documentation JavaDoc comment + function signature /** * Creates and returns HTML for a super awesome button * @methodOf MyObject * @param {String} id The id to give the * @param {String} text The text of the * @param {Function} click (Optional) The onclick event handler for the button * @returns {jQuery} HTML for a button */ function buttonMaker(id, textclick) { Examples Here is how you use the MyObject.buttonMaker method function click(event) { alert('Hello world.'); } var button1 = MyObject.buttonMaker('button1', 'Hello World', click); // equivalent to the above var button2 = MyObject.buttonMaker('button2', 'Hello World'); button2.click(click); Class Template Class template could be just a list of public methods, as well as a brief paragraph describing the class. Inserting Method Templates inside the class template and using Show/Hide highly favored: Comments Cheap organization. I was trying to think of something that would be easiest to use and easiest to set up, this is what I came up with. :The obvious problem is: define $.ajax using this approach. Is the result (a giant, multi-screen javadoc comment with no HTML formatting at all) legible and easy to absorb at a glance? :The second problem is inconsistency. Different people have different ideas about what is "obvious" and not worth writing down or not. The template design reminds people to consider all the possible implications of their code, especially if they've been lazy by not actually considering what exceptions their code throws, or what types of return values it returns and when, or whether their function is prototypical or closured, etc. :IMHO, I feel that your proposed approach is easy to write but painful to read, which is the wrong way around. The page will (should) be read more often then it is modified otherwise the library is unstable, so being more difficult to write is less important then being comprehensive in coverage and easy to read. Lunarity 03:52, November 8, 2012 (UTC) ::A question to both of you: Could you live with this template? It's loosely based on Lunarity's earlier sketch. I'm relatively happy with it. There are certain things I'd like to add that probably cannot be done with templates though. ::It doesn't seem to be possible to pull the H3/4 into the template without breaking the "edit section" link. ::It's also not possible to template the source tag in a useful way. ::pecoes 03:56, November 08, 2012 (UTC) :::I don't fully remember but I believe template parameters are parsed before the template is expanded which is not what you want. The source tag itself also functions as a pre tag, you'd have to use }|lang=javascript}} to get around that, but the wikitext expansion can still bite you with that. :::Headings in templates are treated as part of the template; editing the section will edit the template, not the page. :::It looks fine to me, there seems to be a lot of white-space in the layout but it doesn't really bother me that much. I notice you introduced usage1/usage2/parameter1/parameter2 instead of just chaining the templates though. That should work fine but it forces you to do a lot of unnecessary copy-paste in the template code and limits the number of parameters. Lunarity 06:37, November 8, 2012 (UTC) ::$.ajax: point taken, my model doesn't have a good answer to that. (That being said, I feel it's a fairly rare use case that can be ignored.) ::Exactly who are you expecting to want to read your documentation? This is a pretty low traffic wiki. Why is it worth this much effort to create "pretty" documentation when you can create documentation that "works" much more quickly with far less effort? ::Or in my case, why wouldn't I just run my code through JSDoc-toolkit to generate auto-documentation, throw up the folder on a file sharing website, and then post the download link? ::: Well, Pecoes is using it with Colors so I'm going to have read it :). It may be used with Preferences as well. ::: Why is it worth this much effort to create "pretty" documentation when you can create documentation that "works" much more quickly with far less effort? This relies on the assumption that bad documentation is better than none which is usually untrue and leads to the counter-question that, if the code comments are good enough on their own, why even have a documentation page? You may as well just point people at the source code since it's exactly the same thing anyway. ::: Generated documentation and code comments are usually a poor substitute for technical writing because the purposes are different. Code comments are supposed to describe what the code does, why it does something this particular way instead of using a different algorithm that may intuitively seem better, and to clarify how it works (name the algorithm or formulas, etc.) if it uses complex logic. These are the sort of things someone would need to know to modify the code. Code documentation is supposed to describe what the code is for and how it is supposed to be used which only partially overlaps with how it works, in so far as the function must do what it says without bugs but the exact how is largely irrelevant (though the big-O may be interesting sometimes). version: comments are white-box, documentation is black-box ::: I'm not really clear on what requires a lot of effort with these templates. Assuming you know how your own code works, you just paste the empty template into the page and fill it in from memory, occasionally double checking that something is right. Filling it in should only take proportional time to the complexity of the function since the template takes care of all the page layout for you, you only need to write the description. It's basically like an infobox for functions. ::: In any case, this was Pecoes' idea. I did something vaguely similar to what you're suggesting, but I'm not convinced that it worked very well. Lunarity 06:37, November 8, 2012 (UTC) ::::I disagree that comments are white-box. Generally speaking, comment headers are black-box. Comments /inside/ the function (not headers) are white-box. What I was proposing was using the comment headers: /** * Black-box description of the function * @param {String} a A letter * @returns {String} Another letter */ function append1(a) { // white-box comments describing implementation details // go /inside/ the function, next to the code they describe } ::::The reason not to direct people to the source code is because there's a whole lot of other crap besides those very useful comment headers. I prefer to isolate those comment headers in a location where they can be read more easily (which is essentially what a Javadoc does). ::::On the point of templates. Template:JsMethod seems to nest Template:JsUsage... with Template:JsParameter inside of that? Do you have any idea how much time I would have to spend reading the documentation for that complex template just to use them? (About as much time as I talk if I keep ranting :P) And then once I know how to use them, I'm just going to use them to write more documentation for a low traffic wiki. ::::To summarize, I would have to read documentation to write documentation that nobody is going to read. I mean, you feel there's a point to that, be my guest. It wouldn't have been my first choice. :::::Hm... okay. I find nested templates rather straightforward to write and use, it's basically just templateA(templateB(1, 2, 3), templateB(1, 2, templateC(6))). Functional languages aren't my preference, LISP and Scheme always felt too abstract, but I never considered it to be particularly complicated... ::::: To summarize, I would have to read documentation to write documentation that nobody is going to read. "nobody is going to read" does circle back to the "why write documentation in the first place" question. If you don't think anyone would be interested enough in your project to read the documentation, why write any at all? Lunarity 08:59, November 8, 2012 (UTC) ::::::A minimum amount of documentation is necessary just to understand one's own codebase. It's not that I don't want to write any documentation at all, I just want to present it in as simple a way as possible. Something that I feel the current template system does not have in my best interests. I suppose I can just do my own thing though. (Reset indent) Speaking for myself: I needed something to document the Colors library. I tried to document it informally, but that turned out messy. So I figured: If I have to create some kind of template anyway, I might as well do it right and create one that's not only useful to me and for this particular project. That's why I asked you guys for your opinion. It didn't turn into something complicated, I think. The documentation for the three templates fits on a single page and is pretty straightforward. -- pecoes 10:19, November 08, 2012 (UTC)